'\" te
.\"  Copyright (c) 2000 Sun Microsystems, Inc.
.\"  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH KSYMS 4D "Dec 11, 2000"
.SH NAME
ksyms \- kernel symbols
.SH SYNOPSIS
.LP
.nf
\fB/dev/ksyms\fR
.fi

.SH DESCRIPTION
.sp
.LP
The file  \fB/dev/ksyms\fR is a character special file that allows read-only
access to an  \fBELF\fR format image containing two sections: a symbol table
and a corresponding string table. The contents of the symbol table reflect the
symbol state of the currently running kernel. You can determine the size  of
the image with the \fBfstat\fR(\|) system call. The recommended method for
accessing the  \fB/dev/ksyms\fR file is by using the  \fBELF\fR access library.
See \fBelf\fR(3ELF) for details.  If you are not familiar with  \fBELF\fR
format, see \fBa.out\fR(5).
.sp
.LP
\fB/dev/ksyms\fR is an executable for the processor on which you are accessing
it. It contains  \fBELF\fR program headers which describe the text and data
segment(s) in kernel memory. Since  \fB/dev/ksyms\fR has no text or data, the
fields specific to file attributes are initialized to \fINULL\fR. The remaining
fields describe the text or data segment(s) in kernel memory.
.sp
.ne 2
.na
\fB\fBSymbol table\fR\fR
.ad
.RS 16n
The  \fBSYMTAB\fR section contains the symbol table entries present in the
currently running kernel. This section is ordered as defined by the \fBELF\fR
definition with locally-defined symbols first, followed by globally-defined
symbols. Within symbol type, the symbols are ordered by kernel module load
time. For example, the kernel file symbols are first, followed by the first
module's symbols, and so on, ending with the symbols from the last module
loaded.
.sp
The section header index (st_shndx) field of each symbol entry in the symbol
table is set to  \fBSHN_ABS,\fR because any necessary symbol relocations are
performed by the kernel link editor at module load time.
.RE

.sp
.ne 2
.na
\fB\fBString table\fR\fR
.ad
.RS 16n
The  \fBSTRTAB\fR section contains the symbol name strings that the symbol
table entries reference.
.RE

.SH SEE ALSO
.sp
.LP
.BR stat (2),
.BR elf (3ELF),
.BR kvm_open (3KVM),
.BR mem (4D),
.BR a.out (5),
.BR kernel (8)
.SH WARNINGS
.sp
.LP
The kernel is dynamically configured. It loads kernel modules when necessary.
Because of this aspect of the system, the symbol information present in the
running system can vary from time to time, as kernel modules are loaded and
unloaded.
.sp
.LP
When you open the  \fB/dev/ksyms\fR file, you have access to an  \fBELF\fR
image which represents a snapshot of the state of the kernel symbol information
at that instant in time. While the \fB/dev/ksyms\fR file remains open, kernel
module autounloading is disabled, so that you are protected from the
possibility of acquiring stale symbol data.  Note that new modules can still be
loaded, however. If kernel modules are loaded while you have the
\fB/dev/ksyms\fR file open, the snapshot held by you will not be updated. In
order to have access to the symbol information of the newly loaded modules, you
must first close and then reopen the  \fB/dev/ksyms\fR file. Be aware that the
size of the \fB/dev/ksyms\fR file will have changed. You will need to use the
\fBfstat()\fR function (see \fBstat\fR(2)) to determine the new size of the
file.
.sp
.LP
Avoid keeping the  \fB/dev/ksyms\fR file open for extended periods of time,
either by using \fBkvm_open\fR(3KVM) of the default namelist file or with a
direct open. There are two reasons why you should not hold  \fB/dev/ksyms\fR
open. First, the system's ability to dynamically configure itself is partially
disabled by the locking down of loaded modules. Second, the snapshot of symbol
information held by you will not reflect the symbol information of modules
loaded after your initial open of  \fB/dev/ksyms\fR.
.sp
.LP
Note that the  \fBksyms\fR driver is a loadable module, and that the kernel
driver modules are only loaded during an open system call. Thus it is possible
to run \fBstat\fR(2) on the  \fB/dev/ksyms\fR file without causing the
\fBksyms\fR driver to be loaded. In this case, the file size returned is
\fBUNKNOWN_SIZE\fR.  A solution for this behavior is to first open the
\fB/dev/ksyms\fR file, causing the  \fBksyms\fR driver to be loaded (if
necessary). You can then use the file descriptor from this open in a
\fBfstat\fR(\|) system call to get the file's size.
.SH NOTES
.sp
.LP
The kernel virtual memory access library (\fBlibkvm\fR) routines use
\fB/dev/ksyms\fR as the default namelist file. See \fBkvm_open\fR(3KVM) for
details.
